home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / AIncludes / DebuggerSupport.a < prev    next >
Text File  |  1996-05-01  |  15KB  |  343 lines
  1. ;
  2. ;    File:        DebuggerSupport.a
  3. ;
  4. ;    Contains:    Public interface to kernel services for debuggers
  5. ;
  6. ;    Version:    Technology:    System 8
  7. ;                Release:    Universal Interfaces 3.0d3 on Copland DR1
  8. ;
  9. ;    Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10. ;
  11. ;    Bugs?:        If you find a problem with this file, send the file and version
  12. ;                information (from above) and the problem description to:
  13. ;
  14. ;                    Internet:    apple.bugs@applelink.apple.com
  15. ;                    AppleLink:    APPLE.BUGS
  16. ;
  17. ;
  18.     IF &TYPE('__DEBUGGERSUPPORT__') = 'UNDEFINED' THEN
  19. __DEBUGGERSUPPORT__ SET 1
  20.  
  21.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  22.     include 'Types.a'
  23.     ENDIF
  24.     IF &TYPE('__KERNEL__') = 'UNDEFINED' THEN
  25.     include 'Kernel.a'
  26.     ENDIF
  27.     IF &TYPE('__MACHINEEXCEPTIONS__') = 'UNDEFINED' THEN
  28.     include 'MachineExceptions.a'
  29.     ENDIF
  30.     IF FOR_SYSTEM8_PREEMPTIVE THEN
  31. ;
  32. ; In addition to the normal kernel API, the kernel provides a set of services
  33. ; which are specific to debuggers.  These services are all accessed through the
  34. ; DebuggerSupport library.
  35. ; This first service is debugger registration and unregistration.  For a debugger
  36. ; to register itself with the kernel, it calls DSRegisterDebugger.  (The kernel
  37. ; allows only one registered debugger; multiple debuggers can be supported
  38. ; externally by registering a dispatching entity as the debugger.)  When a debugger
  39. ; has successfully registered itself, it is able to receive exceptions from
  40. ; debuggable tasks.  Unregistering is simply the reverse of registering.  The
  41. ; kernel automatically unregisters a debugger when it terminates if the debugger
  42. ; has not already unregistered itself.  DSRegisterDebugger should be the first
  43. ; call made to this library.
  44. ; To receive an exception, the debugger calls DSWaitForException, passing it a
  45. ; pointer to a DSExceptionRecord and a time limit.  This call blocks until either
  46. ; an exception arrives or the time limit expires (pass kDurationForever to wait
  47. ; indefinitely).  Note that this semantic essentially requires the debugger to
  48. ; be multithreaded.
  49. ; A DSExceptionRecord contains the ID of the excepted task, along with the IDs
  50. ; of the task's team and address space, and a message ID corresponding to the
  51. ; particular exception.  The details of the exception are contained in the
  52. ; exception record's ExceptionInformation structure, which includes pointers
  53. ; to the task's registers and other exception state.  The debugger may directly
  54. ; modify this exception data, and, within limits, these changes will be forced
  55. ; into the task's state upon resuming execution.  (Changes to certain parts of
  56. ; the exception data, such as the privileged and interrupt enable bits of the
  57. ; exception MSR, will be ignored.)
  58. ; DSResumeFromException is used to resume the excepted task's execution or to
  59. ; propagate the exception on.  It takes as parameters the exception ID and an
  60. ; exception return status.  The status may be either noErr or any nonzero error
  61. ; code.  noErr signifies that the debugger has cured the exception and the excepted
  62. ; task should continue execution, using the state from the exception data.  Any
  63. ; other status value will cause the exception to be propagated to the installed
  64. ; exception handler, if any.  If there is no installed handler, or if that handler
  65. ; fails to cure the exception, the exception is again presented to the debugger in
  66. ; another message.  This time, returning a nonzero return status will cause the
  67. ; task to be terminated.  (Double notification of exceptions allows a debugger to
  68. ; catch exceptions either first, last, or at both times.)
  69. ; Not all exceptions will be sent to the debugger.  Exceptions in kernel tasks
  70. ; or in kernel code which runs on behalf of user tasks is not debuggable through
  71. ; normal means.  Furthermore, exceptions occurring in privileged tasks with
  72. ; hardware interrupts disabled, or during execution at secondary interrupt level,
  73. ; or while running message system Accept functions, fall into the same category
  74. ; as kernel exceptions and are not sent to the debugger.
  75. ; The debugger may call DSHoldTasks to request the kernel to hold a task or set
  76. ; of tasks, making them ineligible for execution.  The tasks are specified with a
  77. ; task ID and scope (task only, task and children, task family, or task team).  If
  78. ; any task to be held is already blocked inside the kernel, e.g. due to a page
  79. ; fault, I/O operation, or message send, holding it will cause it to remain
  80. ; ineligible even after it has unblocked.  Releasing held tasks with DSReleaseTasks
  81. ; allows them to become eligible again.
  82. ; DSGetTaskState is used to determine a task's scheduler state (runnable or blocked),
  83. ; and, if blocked, what its PC and SP values were at the point it blocked.  If a
  84. ; task is running a software interrupt it will have scheduler state for both its
  85. ; normal execution and the execution of the software interrupt.
  86. ; DSReadMemory and DSWriteMemory are used to access task memory.  To read memory,
  87. ; the debugger simply calls DSReadMemory.  To modify memory, the debugger must first
  88. ; call DSCreateMemoryAccess to obtain a memory write access right to the desired page
  89. ; of memory.  Using that access right, it may then call DSWriteMemory to perform the
  90. ; modification.  DSWriteMemory performs appropriate processor cache synchronization and
  91. ; backing storage coordination to support modifying code memory, e.g. for instruction
  92. ; breakpoints.  DSDeleteMemoryAccess is used to release an access right.
  93. ; Some implementations of the kernel and hardware may support data breakpoints.  To
  94. ; find out what data breakpoint support (if any) is available, the debugger calls
  95. ; DSGetDataBreakpointInformation.  DSSetDataBreakpoint is used to set or clear a
  96. ; data breakpoint.  The implementation may cause excess exceptions which will have to
  97. ; be filtered out by the debugger:  breakpoints may occur in the wrong address space
  98. ; or on an address which is outside the range specified but which lies within the
  99. ; resolution range supported by the implementation.
  100. ; Exception notification record
  101. ;
  102. DSExceptionRecord        RECORD 0
  103. exceptedTaskID             ds.l    1                ; offset: $0 (0)
  104. exceptedKernelProcessID     ds.l    1                ; offset: $4 (4)
  105. exceptedTaskAddrSpaceID     ds.l    1                ; offset: $8 (8)
  106. exceptionID                 ds.l    1                ; offset: $C (12)
  107. exception                 ds        ExceptionInformation ; offset: $10 (16)
  108. sizeof                     EQU *                    ; size:   $24 (36)
  109.                         ENDR
  110. ; typedef struct DSExceptionRecord *    DSExceptionRecordPtr
  111.  
  112. ;  Task state record
  113. DSKernelState            RECORD 0
  114. kernelState                 ds.l    1                ; offset: $0 (0)
  115. PC                         ds.l    1                ; offset: $4 (4)
  116. SP                         ds.l    1                ; offset: $8 (8)
  117. sizeof                     EQU *                    ; size:   $C (12)
  118.                         ENDR
  119. ; typedef struct DSKernelState *        DSKernelStatePtr
  120.  
  121. DSTaskState                RECORD 0
  122. taskState                 ds        DSKernelState    ; offset: $0 (0)
  123. swiState                 ds        DSKernelState    ; offset: $C (12)
  124. sizeof                     EQU *                    ; size:   $18 (24)
  125.                         ENDR
  126. ; typedef struct DSTaskState *            DSTaskStatePtr
  127.  
  128. ;  ID to specify write access rights to a particular page in logical memory
  129.  
  130.  
  131. ;  SchedulerState values
  132.  
  133. kInactiveState                    EQU        '    '
  134. kPageFaultState                    EQU        'PFLT'
  135. kMessageSendState                EQU        'MSND'
  136. kMessageReceiveState            EQU        'MRCV'
  137. kHeldState                        EQU        'HELD'
  138. kEventFlagState                    EQU        'EFLG'
  139. kTerminatingOtherProcessState    EQU        'OTRM'
  140. kTerminatingCurrentProcessState    EQU        'CTRM'
  141. kTimerDelayState                EQU        'DLYQ'
  142. kKernelQueueState                EQU        'QBLK'
  143. kRunState                        EQU        'RUN '
  144. kSemaphoreReadState                EQU        'MSRD'
  145. kSemaphoreWriteState            EQU        'MSWR'
  146. kTaskStartingState                EQU        'STRT'
  147. kTaskTerminatingState            EQU        'TERM'
  148. ;
  149. ; Describes the data breakpoint facility provided by the current implementation.
  150. ; maxBreakpoints is the maximum number of data breakpoints available (may be zero).
  151. ; breakpointResolution determines the worst case range of addresses to which a data
  152. ; breakpoint applies, as follows:  if the nominal breakpoint address is addr, the
  153. ; actual range of addresses breakpointed may, in the worst case, be
  154. ;    [(addr & ~(breakpointResolution - 1)) ..
  155. ;            (addr & ~(breakpointResolution - 1)) + breakpointResolution - 1].
  156. ;
  157. DSDataBreakpointInformation RECORD 0
  158. maxBreakpoints             ds.l    1                ; offset: $0 (0)
  159. breakpointResolution     ds.l    1                ; offset: $4 (4)
  160. sizeof                     EQU *                    ; size:   $8 (8)
  161.                         ENDR
  162. ; typedef struct DSDataBreakpointInformation * DSDataBreakpointInformationPtr
  163.  
  164.  
  165. kDataBreakpointInformationVersion EQU    1
  166. ;
  167. ; The access types to which a data breakpoint should apply.  Use
  168. ; kDSBreakDisable to clear a data breakpoint.  Note that the implementation
  169. ; may not support breakpointing read and write accesses independently; in
  170. ; that case specifying either option will have the same effect (break on
  171. ; any access).
  172. ;
  173. ; typedef OptionBits                     DSDataBreakpointOptions
  174.  
  175.  
  176. kDSBreakDisable                    EQU        $00000000
  177. kDSBreakOnReadAccess            EQU        $00000001
  178. kDSBreakOnWriteAccess            EQU        $00000002
  179. ;
  180. ; Debugger Services functions
  181. ; Register the debugger.  Returns kernelIDErr if there is already a debugger
  182. ; registered.
  183. ;
  184. ;
  185. ; extern OSStatus DSRegisterDebugger(void )
  186. ;
  187.     IF GENERATINGCFM THEN
  188.         IMPORT_CFM_FUNCTION DSRegisterDebugger
  189.     ENDIF
  190.  
  191. ;
  192. ; Unregister the debugger.  This is also done automatically by the kernel if
  193. ; the debugger terminates.
  194. ;
  195. ;
  196. ; extern OSStatus DSUnregisterDebugger(void )
  197. ;
  198.     IF GENERATINGCFM THEN
  199.         IMPORT_CFM_FUNCTION DSUnregisterDebugger
  200.     ENDIF
  201.  
  202. ;  Wait specified amount of time for an exception message from the kernel.
  203. ;
  204. ; extern OSStatus DSWaitForException(DSExceptionRecord *exceptionRecord, Duration timeLimit)
  205. ;
  206.     IF GENERATINGCFM THEN
  207.         IMPORT_CFM_FUNCTION DSWaitForException
  208.     ENDIF
  209.  
  210. ;
  211. ; Resume execution of a task halted by an earlier exception.  If exceptionReturnStatus
  212. ; is noErr, resume the task, else propagate the exception.  If the propagated exception
  213. ; remains unhandled, a second exception notification will be generated.
  214. ;
  215. ;
  216. ; extern OSStatus DSResumeFromException(MessageID exceptionID, OSStatus exceptionReturnStatus)
  217. ;
  218.     IF GENERATINGCFM THEN
  219.         IMPORT_CFM_FUNCTION DSResumeFromException
  220.     ENDIF
  221.  
  222. ;  Make the specified task(s) ineligible for execution, until released by DSReleaseTasks.
  223. ;
  224. ; extern OSStatus DSHoldTasks(TaskID taskID, TaskRelationship scope)
  225. ;
  226.     IF GENERATINGCFM THEN
  227.         IMPORT_CFM_FUNCTION DSHoldTasks
  228.     ENDIF
  229.  
  230. ;  Make the specified held task(s) eligible again for execution.
  231. ;
  232. ; extern OSStatus DSReleaseTasks(TaskID taskID, TaskRelationship scope)
  233. ;
  234.     IF GENERATINGCFM THEN
  235.         IMPORT_CFM_FUNCTION DSReleaseTasks
  236.     ENDIF
  237.  
  238. ;
  239. ; Get the scheduler state for a task.   The task may be in a software interrupt or in
  240. ; normal execution; if normal, state->swiState.kernelState will be kInactiveState.  In
  241. ; either case, the appropriate state->taskState.kernelState or state->swiState.kernelState
  242. ; will be kRunState if the task is running, and if so the corresponding PC and SP values
  243. ; are invalid and will be returned as zero.  If the task is blocked in normal execution
  244. ; then state->taskState.PC and state->taskState.SP will reflect the PC and SP at the time
  245. ; of the system call which caused the task to block.  Similarly, if the task is blocked
  246. ; in a software interrupt, hence not running, then state->swiState.PC and state->swiState.SP
  247. ; will be nonzero.
  248. ;
  249. ;
  250. ; extern OSStatus DSGetTaskState(TaskID taskID, DSTaskState *state)
  251. ;
  252.     IF GENERATINGCFM THEN
  253.         IMPORT_CFM_FUNCTION DSGetTaskState
  254.     ENDIF
  255.  
  256. ;
  257. ; Create a write access right to the page for logical address dstAddr in address
  258. ; space addrSpaceID.  This makes the page physically resident and prevents subsequent
  259. ; reads or writes of the page from or to backing storage.  The access right is returned
  260. ; in memAccessID.
  261. ;
  262. ;
  263. ; extern OSStatus DSCreateMemoryAccess(AddressSpaceID addrSpaceID, LogicalAddress dstAddr, DSMemoryAccessID *memAccessID)
  264. ;
  265.     IF GENERATINGCFM THEN
  266.         IMPORT_CFM_FUNCTION DSCreateMemoryAccess
  267.     ENDIF
  268.  
  269. ;
  270. ; Modify the memory to which an access right has been obtained.  memAccessID is the access
  271. ; right, dstAddr is the target address, srcDataPtr points to the source data to be written,
  272. ; and numBytes is the size of the write.  The range [dstAddr..dstAddr + numBytes - 1] must lie
  273. ; entirely within the page specified by the access right.  If the destination memory is code,
  274. ; processor caches will be synchronized appropriately.
  275. ;
  276. ;
  277. ; extern OSStatus DSWriteMemory(DSMemoryAccessID memAccessID, LogicalAddress dstAddr, void *srcDataPtr, ByteCount numBytes)
  278. ;
  279.     IF GENERATINGCFM THEN
  280.         IMPORT_CFM_FUNCTION DSWriteMemory
  281.     ENDIF
  282.  
  283. ;
  284. ; Delete an access right and allow normal backing storage activity for that page.  memAccessID
  285. ; is the access right.  Note: changes to the page up to this point will NOT be written to
  286. ; backing storage.
  287. ;
  288. ;
  289. ; extern OSStatus DSDeleteMemoryAccess(DSMemoryAccessID memAccessID)
  290. ;
  291.     IF GENERATINGCFM THEN
  292.         IMPORT_CFM_FUNCTION DSDeleteMemoryAccess
  293.     ENDIF
  294.  
  295. ;
  296. ; Read memory.  srcAddr is the address to read from, addrSpaceID specifies the address space,
  297. ; dstDataPtr points to the debugger buffer into which to copy the data, and numBytes is the
  298. ; size of the read.
  299. ;
  300. ;
  301. ; extern OSStatus DSReadMemory(AddressSpaceID addrSpaceID, LogicalAddress srcAddr, void *dstDataPtr, ByteCount numBytes)
  302. ;
  303.     IF GENERATINGCFM THEN
  304.         IMPORT_CFM_FUNCTION DSReadMemory
  305.     ENDIF
  306.  
  307. ;
  308. ; Set a data breakpoint.  addrSpaceID specifies the address space, which may or may not be
  309. ; used.  breakAddr is the logical address to break on.  numBytes is a hint as to the range
  310. ; of addresses to break on.  The address range [breakAddr .. (breakAddr + numBytes -1)] must
  311. ; lie within the worst case data breakpoint resolution which the implmentation supports, as
  312. ; determined via DSGetDataBreakpointInformation.  A data breakpoint hit will result in a
  313. ; memory access exception of type kDataBreakpointException.  The implementation may cause
  314. ; excess exceptions which will have to be filtered out by the debugger, e.g. breakpoints
  315. ; may occur in the wrong address space or on an address which is outside the range specified
  316. ; but which lies within the resolution range supported by the implementation.  To "fix up"
  317. ; a memory reference which triggered a data breakpoint exception without removing the
  318. ; data breakpoint, use DSReadMemory or DSWriteMemory.  Data breakpoints may be disallowed
  319. ; on certain addresses which are used by system code; DSSetDataBreakpoint will return
  320. ; kernelInUseErr for such addresses.
  321. ;
  322. ;
  323. ; extern OSStatus DSSetDataBreakpoint(AddressSpaceID addrSpaceID, LogicalAddress breakAddr, ByteCount numBytes, DSDataBreakpointOptions options)
  324. ;
  325.     IF GENERATINGCFM THEN
  326.         IMPORT_CFM_FUNCTION DSSetDataBreakpoint
  327.     ENDIF
  328.  
  329. ;
  330. ; Get information about data breakpoint support.  Returns the number of breakpoints available in
  331. ; the current implementation and the worst case address resolution of a data breakpoint.
  332. ;
  333. ;
  334. ; extern OSStatus DSGetDataBreakpointInformation(PBVersion version, DSDataBreakpointInformation *info)
  335. ;
  336.     IF GENERATINGCFM THEN
  337.         IMPORT_CFM_FUNCTION DSGetDataBreakpointInformation
  338.     ENDIF
  339.  
  340.     ENDIF
  341.     ENDIF ; __DEBUGGERSUPPORT__ 
  342.  
  343.